home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / printq.exe / READ.ME < prev    next >
Encoding:
Text File  |  1993-05-23  |  10.4 KB  |  237 lines
  1. This file contains the following, released to the public domain:
  2.  
  3.     PRINTQ.H:        Header for PrintJob, PrintQueue classes, and the PrintJob-
  4.                     derived classes PrintBuffer and PrintFile.
  5.  
  6.     PRINTAPP.H:        Header for using the print queue classes with Turbo Vision;
  7.                     includes classes TPrintAppInit, TPrintApp and TPrintQueue.
  8.  
  9.     PRINTQ.CPP:        Source for classes declared in PRINTQ.H.
  10.  
  11.     PRINTAPP.CPP:   Source for classes declared in PRINTAPP.H
  12.  
  13.     MAIN.CPP:        Source for sample program.
  14.  
  15. These files show how to allow a Turbo Vision application to perform quasi-
  16. background printing. Its not truly background printing, because small blocks
  17. of text are printed during the application's idle() function. This means that
  18. if there is a significant amount of time between calls to getEvent() that no
  19. printing will be performed (IE if you're doing long calculations, or excessive
  20. file i/o).
  21.  
  22. WARNING!!! The demo program (main.cpp) uses the class TPrintQueue, which
  23. defines the printing operation to be performed by using DOS calls to print;
  24. there is a bug in the TV library with TSystemError when a print error occurs
  25. (run out of paper, printer is off-line, etc); if you use the TPrintQueue
  26. presented here (or any time you use DOS to print in a TV app), you need to
  27. fix the bug in TV. This entails:
  28.     1) In the header file SYSTEM.H, line 366: change:
  29.         static const char * const near errorString[14];
  30.     to have one more string:
  31.         static const char * const near errorString[15];
  32.  
  33.     2) In the file TVTEXT2.CPP, line 138: add:
  34.         ...
  35.         "Insert diskette in drive %c", // add the comma
  36.         "Printer not responding"       // add this line
  37.         };
  38. This is for versions of TV 1.03 and below; you'll have to check any future
  39. versions to see if this has been corrected.
  40.  
  41. ---------------------------------------------------------------------
  42.  
  43.     The concept is rather simple. The class TPrintApp is derived from
  44. TApplication, and virtually from TPrintAppInit. This means that you have to
  45. specifically initialize TPrintAppInit in your app's ctor (just like with
  46. TProgInit class). All that TPrintAppInit does (again, like TProgInit) is allow
  47. a method for your class' ctor to initialize the static PrintQueue member. The
  48. demo program shows how to do this.
  49.  
  50.     Class TPrintApp overrides the following functions, for the following
  51. reasons:
  52.  
  53.     shutDown(): overridden to clean up printQueue.
  54.  
  55.     idle(): this method gets called whenever TV is waiting for input (IE the
  56.         app is "idle"). Since the app's just sitting there doing nothing,
  57.         we call upon the printQueue to print() a small block of text. If you
  58.         use the TPrintQueue class included (or another that uses DOS to print)
  59.         and an error occurs, TV's TSystemError will overlay the statusline
  60.         with an error message, allowing the user to retry or cancel.
  61.  
  62.     handleEvent(): overridden to allow an easy method to add print jobs to the
  63.         queue. If an evCommand event is received (command cmAddPrintJob),
  64.         this method casts the event.message.infoPtr to a PrintJob pointer,
  65.         ensures its not null, ensures it actually has something to print
  66.         (in case its ctor failed), ensures that there's a queue to put it
  67.         into, and inserts it into the queue. If all of this passes, then
  68.         the event is cleared; otherwise the PrintJob pointer is deleted
  69.         (important to note!) and the event is NOT cleared. This makes it so
  70.         that the calling function can check message()'s return value to ensure
  71.         that the job was added to the queue; if message() returns 0, then the
  72.         job has been deleted and NOT added to the queue.
  73.  
  74.     valid(): overridden to see if printing is still going on when cmQuit is
  75.         issued. If there are still jobs in the queue when the app tries to
  76.         quit, valid() issues a messageBox warning the user that printing is
  77.         still going on and whether or not to cancel printing.
  78.  
  79. Class TPrintApp also adds the following:
  80.  
  81.     initPrintQueue(): this *static* method is passed by default to
  82.         TPrintAppInit() as the default function which will create a PrintQueue
  83.         when called. If you want to use a different PrintQueue-derived class
  84.         (note that PrintQueue is a pure class and cannot be instantiated)
  85.         then just define a function which returns one of your objects and
  86.         pass it to TPrintAppInit() in your app's ctor initialization list.
  87.         Its best (encapsulation) to make this function a static method of your
  88.         app.
  89.  
  90.     printQueue: this static variable is the print queue. Its assigned in
  91.         TPrintApp's ctor by a call to createPrintQueue() - which is the same
  92.         function you passed to TPrintAppInit().
  93.  
  94. Class TPrintQueue:
  95.     This class is derived from PrintQueue. All it does is to override the
  96. pure virtual method printString() to use DOS to print.
  97.  
  98. Class PrintQueue:
  99.     This class is a simple collection of PrintJobs, defining the following
  100. operations:
  101.  
  102.     Ctor/dtor: the default ctor (ie PrintQueue()) just initializes the queue
  103.         as empty; the dtor (~PrintQueue()) calls killAll() to kill (delete)
  104.         all jobs in the queue.
  105.  
  106.     insert(): returns True if the job is not null and is inserted successfully
  107.         into the queue; otherwise returns False.
  108.  
  109.     kill(): kills (deletes) the job if its in the queue. Also: if the job is
  110.         the current job and its already started printing, calls the virtual
  111.         method printFormFeed() to eject the current page from the printer.
  112.  
  113.     killAll(): calls kill() for each job in the queue, then frees all memory
  114.         being used by the queue.
  115.  
  116.     currentJob(): return a pointer to the current job; if there isn't one
  117.         (queue is empty) returns null.
  118.  
  119.     print(): does nothing if the queue is empty; otherwise it calls upon the
  120.         current job to set a char* to the text to print and to return the
  121.         length of that text (note that the amount of text printed per call
  122.         to print() is determined by the PrintJob, not by the queue). If the
  123.         char* was not set to null and the length was > 0, then calls the
  124.         virtual method printString() to print the text, and then tells the
  125.         job to skip() the number of bytes that were actually printed by
  126.         printString(). If the job is now complete() (all its text printed)
  127.         then the current job is deleted (with kill()), printFormFeed() is
  128.         called, and now the next job (if there is one) is ready to be
  129.         printed on the next call to print().
  130.  
  131.     printString(): this is a pure virtual function - any class derived from
  132.         PrintQueue MUST override this function to perform the actual printing.
  133.         It should accept a const char* to the text to print, and an int to
  134.         the length of the text; it should return the number of bytes printed.
  135.  
  136.     printFormFeed(): virtual; the default printFormFeed() just does:
  137.         return Boolean( printString("\f",1) == 1);
  138.  
  139.     setJobsSize(): called upon to expand the internal buffer when a job is
  140.         added to the queue.
  141.  
  142.     jobs: buffer which holds the PrintJob pointers. jobs[0] is the current
  143.         job.
  144.  
  145.     count: number of items in the queue.
  146.  
  147.     limit: number of items that can be stored in jobs.
  148.  
  149.  
  150. Class PrintJob:
  151.     This class by default does nothing. To be useful, its virtual methods must
  152. be overridden by a derived class.
  153.  
  154.     Ctor/dtor: the ctor requires that you pass it the printSize - this is the
  155.         maximum number of bytes that will be returned by getText() (ie the
  156.         maximum bytes printed at a time). This number should not be too big
  157.         or it will slow down TV. My demo (run on a 386-33) uses 128 bytes,
  158.         and ran fine. For faster/slower machines, you may have to experiment
  159.         to find a good size. The dtor is virtual, and does nothing.
  160.  
  161.     reset(): just repositions pos back to 0.
  162.  
  163.     getText(): does nothing; in a useful derivative class, this method will
  164.         set the buf argument to point to the text to be printed (pos indicates
  165.         the current position) and returns the length of the bytes to be
  166.         printed. This returned value should be <= printSize.
  167.  
  168.     skip(): increments pos by the passed argument (pos += n). If this sets
  169.         pos past the size, pos is set to size. Whenever the PrintQueue
  170.         successfully prints some chars, it will call this function to increment
  171.         the current print starting position.
  172.  
  173.     complete(): Returns True if the job has been completed, False otherwise.
  174.         By default, a job is completed if pos >= size.
  175.  
  176.     amountPrinted(): Returns the number of bytes that have been skip()d.
  177.  
  178.     amountRemaining(): Returns the number of bytes that still remain to be
  179.         printed; IE size-pos.
  180.  
  181.     pos: the current print start location.
  182.  
  183.     size: the total number of bytes in the job. By default, this is 0; to be
  184.         useful, a derived class needs to set this to the number of bytes in
  185.         the job (for a file, the file length; for a buffer, the buffer size,
  186.         etc).
  187.  
  188.     printSize: this is the argument that was passed to the ctor; indicates
  189.         the maximum number of bytes that should be returned by getText().
  190.  
  191. ---------------------------------------------------------------------
  192.  
  193. I've also included 2 'standard' PrintJob-derived classes: one to print a
  194. contiguous buffer, and one to print a file.
  195.  
  196. Class PrintBuffer:
  197.     This class allows you to print a char* buffer that's in memory.
  198.  
  199.     Ctor/dtor: the ctor is passed a pointer to the buffer, its size, and
  200.         the printSize for the base PrintJob ctor. The dtor will delete the
  201.         buffer when its done, so the buffer must be a heap object (allocated
  202.         by a call to the global new(size_t) operator. Sets size to the size
  203.         of the buffer.
  204.  
  205.     getText(): overridden to point the buf argument to the current print loc
  206.         in the buffer; that is, buffer+pos. Returns printSize, unless there
  207.         are less than printSize bytes remaining in the buffer - then it
  208.         returns size-pos.
  209.  
  210.     buffer: points to the buffer that was passed to the ctor.
  211.  
  212. Class PrintFile:
  213.     This class allows you to print a file.
  214.  
  215.     Ctor/dtor: the ctor is passed a pointer to the file's name, as well as
  216.         the printSize for the base PrintJob ctor. It will allocate an internal
  217.         buffer (size printSize) and open the file for shared access (read-only
  218.         and share:deny writes). If the allocation or the open fails, deletes
  219.         the buffer, sets handle to -1, and size to 0. Otherwise it sets size
  220.         to the filelength() of the file. The dtor will close() the handle
  221.         (if it open()d successfully) and delete the internal buffer.
  222.  
  223.     getText(): overridden to point to the internal buffer; then returns the
  224.         number of bytes read() from the handle into the buffer, attempting to
  225.         read printSize bytes.
  226.  
  227.     handle: file handle.
  228.  
  229.     buffer: internal buffer.
  230.  
  231.  
  232. If you have any problems, leave me a message in the BCPPDOS forum, in the
  233. TV section (section 11).
  234.  
  235.     Pat Reilly
  236.     71333,2764
  237.